Skip to main content

ListSignalEventsV1

A POST request that retrieves a list of your organization's Signal events. The endpoint is https://api.aware.work/external/signal/events/v1.

Access​

To access this operation, your API token must have one of the following permissions:

For more information, see the API token documentation.

Request Format​

Despite being a list operation that does not modify resources, ListSignalEventsV1 is a POST call.

Parameters​

None of the below parameters are required. However, they can assist you in selecting the data you're looking for much more easily and efficiently than paging through all events depending on your use-case.

Note:

  • If a filter field is not provided, no filtration is performed on the corresponding field
  • If a filter field allows you to pass a list of items, events with a field matching any of the items will be returned
    • For example, passing remediationTypes: ['Delete', 'Notify'] will return all events with either (or both) of the Delete and Notify remediation types.
  • If multiple filter fields are provided, events must match all filters in order to be returned
    • For example, setting both startEventCreationTime and endEventCreationTime will return only events created between those two times.
ParameterRequiredDescriptionTypeFormat / Options
sortFieldNoThe field by which events will be sorted; Defaults to ContentTimestringContentTime / EventCreatedTime / EventStatus / RuleName
sortOrderNoThe order in which events will be sorted; Defaults to DescendingstringAscending / Descending
startEventCreationTimeNoSelects events that happened at or after (>=) the provided timestringyyyy-MM-ddTHH:mm:ss
endEventCreationTimeNoSelects events that happened at or before (<=) the provided timestringyyyy-MM-ddTHH:mm:ss
startContentTimeNoSelects events for content that was created or modified at or after (>=) the provided timestringyyyy-MM-ddTHH:mm:ss
endContentTimeNoSelects events for content that was created or modified at or before (<=) the provided timestringyyyy-MM-ddTHH:mm:ss
policyIdsNoSelects events for a given list of policy IDslist[string]strings must be in uuid4 format
ruleIdsNoSelects events for a given instance of a Rulelist[string]strings must be in uuid4 format
ruleFamilyIdsNoSelects events for a given rule; this is the Rule ID that is displayed in the UIlist[string]strings must be in uuid4 format
contentTypesNoSelects events for the given Content TypesstringFile / Image / Message / Form / Survey
contentPlatformIdsNoSelects events for the given Platform IDslist[string]strings must be in uuid4 format
remediationTypesNoSelects events for the given Remediation TypesstringClean / Delete / Hold / Notify / NotifyCustom / NotifyAuthor / NotifyAuthorCustom / NotifyManager / NotifyManagerCustom / Purge / PurgeIgnoreHold / Tag / Quarantine / Unquarantine / NotifyViaBot / CleanArchiveOnly
contentGroupScopesNoSelects events for the given Group ScopesstringCommonForum / DirectForum / PersonalFeed / PrivateForum / PublicForum / SpecificForum / PublicEvent / PrivateEvent / PersonalFileCollection / SharedFileCollection / PublicGeneric / PrivateGeneric
isQuarantinedNoSelects events that are either quarantined (true) or not quarantined (false)boolean
maxItemCountNoSets the maximum amount of events that will be returned; Defaults to 100intinteger between 1 and 300 inclusive
continuationTokenNoToken used to continue a query if the results could not be returned in a single responsestring

Query​

Below is the request in its most basic form. See request samples for more advanced query examples.

curl -X POST --location "https://api.aware.work/external/signal/events/v1" \
    -H "X-Aware-Api-Key: ${API_TOKEN}" \
    -H "Content-Type: application/json" \
    -d "{}"

Response Format​

If your request was successfully executed, the endpoint will return an HTTP 200 status and a response similar to the one below:

{
  "signalEventList": [
    {
      "signalEventId": "3d8e79d4-53e3-5752-9b74-bb17fed5a17a",
      "signalEventDetails": {
        "tenantId": "76e682cf-762f-467b-bb9c-47d2852ec4c6",
        "policyDetails": {
          "policyId": "4b34bca9-adf5-5a7c-3121-e6e84ac7f696",
          "policyName": "My Sample Policy",
          "createdTime": "2023-07-04T20:10:29.729023Z",
          "deletedTime": null
        },
        "inspectionRequestId": "0d80d1dc-1514-d0ea-a243-5d14fdf48156",
        "eventStatus": "Open",
        "isQuarantined": false,
        "createdTime": "2023-10-12T15:28:41.5849368Z",
        "deletedTime": null,
        "signalRuleDetails": {
          "ruleId": "5174a601-aafd-3a5e-f58a-00a38cfd0527",
          "ruleFamilyId": "5206c8fe-7306-dbdd-41b9-f454c71f46e8",
          "ruleName": "My Sample Rule",
          "ruleBehavior": "Negative",
          "ruleRemediations": [],
          "ruleSnippets": [
            {
              "snippetStart": 2,
              "snippetLength": 8,
              "snippetContent": "This is a sample rule snippet!"
            }
          ],
          "ruleDetectionPositions": [
            {
              "search": "snippet!",
              "detectionStart": 2,
              "detectionLength": 8
            }
          ],
          "ruleConditionMatches": [
            "5174a601-aafd-3a5e-f58a-00a38cfd0527",
            ...
          ]
        },
        "contentObjectDetails": {
          "contentObjectId": "9c40fce9-4679-646c-e471-84451b2f8526",
          "contentObjectType": "Message",
          "contentTime": "2023-10-12T14:30:11.379Z",
          "contentPlatformId": "aff8ecc4-df30-6d5b-d1d9-d6cb9a43cd50",
          "contentGroupDetails": {
            "contentGroupTag": "G014QM4NUCR",
            "contentGroupName": "my-example-group",
            "contentGroupScope": "PrivateForum"
          },
          "contentAuthorDetails": {
            "contentAuthorId": "853c4b29-6079-42b5-8606-3fe6277d63fd",
            "contentAuthorName": "Aware Example",
            "contentAuthorEmail": "aware@example.com"
          },
          "contentObjectIsChat": true,
          "contentObjectIsThread": false
        }
      }
    },
    ...
  ],
  "continuationToken": "..."
}

Note that if the continuation token is included in the response and is not null, there are more events available for you to page through. In order to get the next page, repeat the same request with the continuation token from the response included:

curl -X POST --location "https://api.aware.work/external/signal/events/v1" \
    -H "X-Aware-Api-Key: ${API_TOKEN}" \
    -H "Content-Type: application/json" \
    -d "{
          ${SAME_REQUEST_BODY_HERE},
          \"continuationToken\": \"${CONTINUATION_TOKEN_FROM_RESPONSE}\"
        }"

Request Samples​

Query for all events on a given day, in ascending order​

curl -X POST --location "https://api.aware.work/external/signal/events/v1" \
    -H "X-Aware-Api-Key: ${API_TOKEN}" \
    -H "Content-Type: application/json" \
    -d "{
          \"sortField\": \"ContentTime\",
          \"sortOrder\": \"Ascending\",
          \"startContentTime\": \"2023-07-04T00:00:00\",
          \"endContentTime\": \"2023-07-05T00:00:00\"
        }"

Find all direct messages that were quarantined by Signal and are still quarantined in the platform​

curl -X POST --location "https://api.aware.work/external/signal/events/v1" \
    -H "X-Aware-Api-Key: ${API_TOKEN}" \
    -H "Content-Type: application/json" \
    -d "{
          \"remediationTypes\": [
            \"Quarantine\"
          ],
          \"contentGroupScopes\": [
            \"DirectForum\"
          ],
          \"isQuarantined\": true
        }"